home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Tools & Apps / Graphics & Imaging / Ultra Dragging 1.0ß1 / Read Me < prev    next >
Encoding:
Text File  |  1991-06-04  |  7.8 KB  |  201 lines  |  [TEXT/MPS ]
  1. Color Icon Dragging Code
  2.  
  3. Files:
  4.  
  5. The core functionality for the dragging of color icons is
  6. in two units: UOffscreenManager and UIconDragging.  MNothing,
  7. UNothing, and UReliefGridView are used in the demonstration
  8. example only.
  9.  
  10. Core Functionality-
  11.  
  12. UOffscreenManager.p
  13. UOffscreenManager.inc1.p
  14. UIconDragging.p
  15. UIconDragging.inc1.p
  16.  
  17. Example-
  18.  
  19. MNothing.p
  20. UNothing.p
  21. UNothing.inc1.p
  22. UReliefGridView.p
  23. Nothing.r
  24. Color.r
  25. NothingResources.rsrc
  26. Nothing.MAMake
  27.  
  28. Built Programs-
  29.  
  30. Nothing            (optimized version)
  31. Nothing.debug    (debugging version)
  32.  
  33. Miscellaneous-
  34.  
  35. Read Me            (this document)
  36.  
  37.  
  38. Quick Install:
  39.  
  40.     The Quick install procedure assumes you have OSImage but
  41.     haven't installed it yet and you want to build the
  42.     sample program right now, without going through the normal
  43.     installation procedure.
  44.     
  45.     Copy the OSImage Pascal interfaces and library to the
  46.     icon dragging folder, rename Nothing.MAMake to
  47.     Nothing.MAMake.complex and Nothing.MAMake.simple to
  48.     Nothing.MAMake.  You may now build the sample program using
  49.     MABuild.
  50.  
  51.  
  52. Installing:
  53.  
  54.     You'll need to acquire and install OSImage from the
  55.     Donoho Design Group.  This library is available from MADA.  If
  56.     you don't have OSImage you'll have to make some modifications
  57.     to the source before it will work.  Good Luck.
  58.     
  59.     Assuming you have OSImage and you've installed it in the
  60.     conventional way you need to modify Nothing.MAMake to build
  61.     the example "Nothing" application.  You need to remove the
  62.     OtherPascalOptions definition and replace {SCPBldgBlksDir},
  63.     {SCPPLibraries}, and {SCPBldgBlksLib} in the OtherLinkFiles
  64.     definition with {MALibraries}, {PLibraries}, and {OSImageLib},
  65.     respectively.
  66.     
  67.     If you haven't installed OSImage conventionally (you may have
  68.     combined it with other libraries or put the definitions and
  69.     libraries in separate places) you need to set {SCPInterfaces}
  70.     and {SCPBldgBlksDir} in the OtherPascalOptions definition to
  71.     the directories that hold the UOSBitmap.p and UOSImage.p
  72.     interfaces, respectively.  In addition, {SCPLibraries} and
  73.     {SCPBldgBlksDir} will have to be set to the directories that
  74.     contain OSBitmap.o and OSImage library directories.
  75.     {SCPBldgBlksLib} must be replaced by the library file that
  76.     contains OSImage.  Note that under many circumstances
  77.     {SCPBldgBlksDir}, or its equivalent, will normally contain
  78.     UOSImage.p, UOSImage.inc1.p, and the various directories that
  79.     contain the differently configured builds of the library
  80.     (e.g., 'Debug Files:', 'Non-Debug Files:', '.S6NmTeSm:', etc.)
  81.     
  82.     
  83. Features:
  84.  
  85. 1)    Works across multiple monitors with multiple screen depths.
  86.  
  87. 2)    Automatically adjusts when either color table or depth of
  88.     the screen's GDevice changes.  These characteristics are
  89.     checked and adjusted in the background by cohandler every
  90.     1/2 second, so there should not normally be a perceptible
  91.     delay when the user starts to drag.  Also, the cohandler
  92.     makes the right thing happen, even if the depths or colors
  93.     were changed without switching in and out of the application
  94.     (e.g., when an FKey like Switch-A-Roo™ is used).
  95.     
  96. 3)    Works with GC accelerator.
  97.  
  98. 4)    Works under System 7.0.
  99.  
  100. 5)    Works on Mac II-class machines.
  101.  
  102.  
  103. Known Problems:
  104.  
  105. 1)    No performance profile or optimizations have been performed.
  106.     However, I feel fairly certain that constraining
  107.     TCIconTracker.fScreenLocusRect such that the offscreen
  108.     bitmaps are aligned will give much better performance.
  109.     Other options include creating an TCIconTracker.fUnderIcon
  110.     of the proper depth for each monitor- another offscreen
  111.     manager, perhaps.
  112.     
  113. 2)    Turning on HS reveals some funny business in the offscreen
  114.     image blitted to the screen, but only the first time through
  115.     the loop.  This has never caused a crash and has never
  116.     been manifested with HS off.
  117.     
  118. 3)    There is no reason why this code should be restricted to
  119.     color icons only.
  120.     
  121. 4)    The arrow cursor flickers, even when the mouse isn't moved.
  122.     This is somewhat annoying.
  123.     
  124. 5)    Failure of ReallocOSImage in TOffscreenDevice.CheckDepthAndColor
  125.     will cause the offscreen images to be of the wrong depth
  126.     and therefore will produce "unusual" coloring effects
  127.     when blitted to the screen.  Preflighting the memory can
  128.     solve this problem.
  129.     
  130. 6)    The code must be checked for proper failure handling.
  131.  
  132. 7)    Needs to be made to work on non-ColorQuickdraw systems that
  133.     don't have color icons.  Note: OSImage does the right thing
  134.     on GWorld-capable and non-GWorld-capable systems (i.e., GWorlds
  135.     are used if they are there, but they are not necessary).
  136.     
  137. 8)    The most serious problem is in TCIconTracker.Free where the code
  138.     to free fMaxDepthGrafPort is commented out, which should cause
  139.     memory leakage.  Unfortunately, uncommenting this code causes
  140.     the system to, eventually, crash when the icon is dropped on
  141.     the desktop, rather than another view.
  142.     
  143. How it works:
  144.  
  145.     Dragging icons is written in Object Pascal and uses MacApp 2.0.x.
  146.     It works by maintaining preallocated offscreen pixmaps, using the
  147.     OSImage package from Donoho Design Group, for each connected "real"
  148.     GDevice which are combined to form a virtual composite pixmap using
  149.     object abstractions.
  150.     
  151.     Essentially, the virtual pixmap mirrors the area of the user-visible
  152.     screen around where the user is dragging the icon.  Before plotting
  153.     the color icon to the virtual pixmap, the area under where the "icon
  154.     to be plotted" is saved in another offscreen pixmap.  As the user
  155.     drags the icon, the saved area under the icon is restored and the
  156.     icon is plotted in the new location in the virtual pixmap, after the
  157.     area under the new location is again saved.  Then, the entire virtual
  158.     pixmap is blasted to the screen, thereby avoiding video flicker.
  159.     
  160.     Dragging icons uses multiple offscreen pixmaps, one for each GDevice,
  161.     for performance reasons, since each GDevice has its own color table
  162.     and depth.  Using one pixmap to mirror all GDevices would require
  163.     QuickDraw to make adjustments for these differences when pixmaps are
  164.     blitted between "incompatible" GDevices.  This is very inefficient.
  165.     Instead, each GDevice has its own compatible pixmap that is used when
  166.     the area around the icon intersects that GDevice.  The virtual
  167.     pixmap abstraction (TOffscreenManager) handles the usage of these
  168.     multiple pixmaps transparently.
  169.     
  170.     One can see the interaction between the GDevice offscreen pixmaps,
  171.     the virtual pixmap, and the pixmap that is saved under the icon
  172.     by running the debug version of "Nothing" and turning on intense
  173.     debugging in the MacApp debugger.  What you will see is that each
  174.     GDevice will continuously plot its contents in the lower right-hand
  175.     corner of its monitor.  At the upper-left of the (0,0) origin monitor
  176.     you will see the composite pixmap plotted, and below that you will see
  177.     the screen contents under the icon.
  178.     
  179.     Another aspect of the usage of offscreen pixmaps of limited size
  180.     in an application such as this is the requirement that as the
  181.     offscreen pixmap moves to mirror a new location of the screen it
  182.     must not move so far as to preclude the restoration of the screen
  183.     where the icon WAS.  That is, the size of the offscreen pixmap
  184.     must encompass the extent of where the icon WAS and where it
  185.     WILL BE in order to erase the old one and plot the new one at
  186.     the same time.  But, since the user can move the cursor arbitrarily
  187.     fast it becomes necessary to constrain the movement of the offscreen
  188.     pixmap, and therefore the icon itself.  Therefore if the user
  189.     moves the cursor very fast he will notice that the icon will lag
  190.     behind his cursor.
  191.     
  192.     Dragging icons also handles most of the tedium of making MacApp
  193.     views aware when an icon is dragged onto it from another view.
  194.     The code is somewhat messy and involves some tricks in the use
  195.     of view focusing but essentially does a FindWindow converts the
  196.     result to a MacApp window and recursively descends the view
  197.     hierarchy to the topmost view.  (Many thanks to Richard Rodseth
  198.     for sample code on how to do this.)
  199.     
  200.     
  201. Geoff Pascoe  4/8/91, 5/23/91, 5/31/91